/*
 *  Copyright 2013 National Institute of Advanced Industrial Science and Technology
 *  
 *  Licensed under the Apache License, Version 2.0 (the "License");
 *  you may not use this file except in compliance with the License.
 *  You may obtain a copy of the License at
 *  
 *      http://www.apache.org/licenses/LICENSE-2.0
 *  
 *  Unless required by applicable law or agreed to in writing, software
 *  distributed under the License is distributed on an "AS IS" BASIS,
 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 *  See the License for the specific language governing permissions and
 *  limitations under the License.
 */

package org.sss.mapreduce;

import org.sss.mapreduce.datatype.Packable;

/**
 * SSS uses <code>Context</code> to communicate with user-defined Mapper/Reducer classes.
 */
public interface Context {
  /**
   * Open SideData
   * <p>
   * User-defined <tt>map</tt>/<tt>reduce</tt> method could access to
   * a small Tuple Group, which we call SideData.
   *
   * @param  gid       The ID of Tuple Group accessed.
   * @param  keyClass  class object for the side data's key class
   * @param  valClass  class object for the side data's value class
   * @return the <code>SideData<K,V></code> object
   */
  <OK extends Packable, OV extends Packable>
  SideData<OK, OV> openSideData(GroupID gid, Class<OK> keyClass, Class<OV> valClass);
  /**
   * Open SideData
   * <p>
   * User-defined <tt>map</tt>/<tt>reduce</tt> method could access to
   * a small set of recoreds, which we call SideData.
   *
   * @param  gid           The ID of Tuple Group accessed.
   * @param  keyClass      class object for the side data's key class
   * @param  valClass      class object for the side data's value class
   * @param  sideDataType
   * @return the <code>SideData<K,V></code> object
   */
  <OK extends Packable, OV extends Packable>
  SideData<OK, OV> openSideData(GroupID gid, Class<OK> keyClass, Class<OV> valClass, String sideDataType);
  /**
   * Get tuples reader.
   *
   * Returns <code>Iterable</code> to read tuple group specified by <code>gid</code>.
   *
   * @param  gid            The ID of Tuple Group accessed.
   * @param  keyClass      class object for the side data's key class
   * @param  valClass      class object for the side data's value class
   * @return the <code>Iterable</code> to read tuple group.
   */
  <OK extends Packable, OV extends Packable>
  Iterable<Tuple<OK, OV>> getTupleReader(GroupID gid, Class<OK> keyClass, Class<OV> valClass) throws SssException;

  /**
   * Scan side data.
   *
   * @param  gid      The ID of Tuple Group scaned.
   * @param  keyClass class object for the side data's key class
   * @param  valClass class object for the side data's value class
   * @param  scaner   listener on reading a tuple.
   */
  <OK extends Packable, OV extends Packable>
  void scanSideData(GroupID gid, Class<OK> keyClass, Class<OV> valClass, TupleGroupScaner<OK, OV> scaner) throws SssException;

  /**
   * Returns the <code>Configuration</code> object associated to this <code>Context</code>
   *
   * @return the <code>Configuration</code> object associated to this <code>Context</code>
   */
  Configuration getConfiguration();
  /**
   * Get a TaskSet variable
   * <p>
   * SSS user applications could use `TaskSet variables' to share
   * some data between jobs.
   *
   * @param  key    a key to retrieve TaskSet variable
   * @param  klass  a class object for the TaskSet variable
   * @return TaskSet variable for the specified key
   */
  <T> T getTaskSetVariable(String key, Class<T> klass);
  /**
   * Set a TaskSet variable
   * <p>
   * SSS user applications could use `TaskSet variables' to share
   * some data between jobs.
   *
   * @param  key  a key for new TaskSet variable
   * @param  v    a value to be set as TaskSet variable
   */
  void setTaskSetVariable(String key, Object v);
  
  
  /**
   * Increment specified counter.
   *
   * The counter will be initialized with 0. 
   * 
   * @param counterName a String to specify counter 
   */
  void incrCounter(Enum<?> counterName, int diff); 
}
